<!DOCTYPE HTML>
<html>
<head>
<title>IniWrite | AutoHotkey</title>
<meta name="description" content="The IniWrite command writes a value or section to a standard format .ini file." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>IniWrite</h1>

<p>写入值到标准格式的 .ini 文件.</p>

<pre class="Syntax">
<span class="func">IniWrite</span>, Value, Filename, Section, Key
<span class="func">IniWrite</span>, Pairs, Filename, Section
</pre>
<h2>参数</h2>
<dl>

  <dt>Value</dt>
  <dd>
    <p>将被写入到 <em>Key</em> 的等号(=) 右边的字符串或数字.</p>
    <p>如果文本较长, 可以通过<a href="../Scripts.htm#continuation">延续片段</a>的方法将其分解成较短的几行, 这样可以增加可读性和可维护性.</p>
    </dd>
  
  <dt>Pairs</dt>
  <dd>
    <p><span class="ver">[AHK_L 57+]:</span> 将 Section 的完整内容写入到 ini 文件中, 不包括 [SectionName] 头部. <em>Key</em> 必须省略. <em>Pairs</em> 不可包含空行. 如果 section 已经存在, 所有从 section 开头直到最后一个 key=value 对之间的内容都被覆盖(译者注: Pairs 内容写入 section 的开头, 最后一个 key=value 对后面的内容不会被覆盖). <em>Pairs</em> 可以是不包含等于符号(=) 的内容, 但这可能产生不一致的效果. 注释可以写入文件, 但是在使用 <a href="IniRead.htm">IniRead</a> 读出时将不包含注释段.</p>
  </dd>

  <dt>Filename</dt>
  <dd><p>ini 文件名, 如果未指定绝对路径则假定在 <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> 中.</p></dd>

  <dt>Section</dt>
  <dd><p>ini 文件中的段名, 它是包含在方括号中的标题短语(在此参数中不需要加方括号).</p></dd>

  <dt>Key</dt>
  <dd><p>ini 文件中的键名.</p></dd>

</dl>
<h2>ErrorLevel</h2>
<p><span class="ver">[v1.1.04+]</span>: 此命令失败时会抛出异常. 想了解更多信息, 请参阅<a href="Catch.htm#RuntimeErrors">运行时错误</a>.</p>
<p>如果遇到问题则 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被置为 1, 否则为 0.</p>
<h2>备注</h2>
<p>可以将超过 65,535 个字符的值写入文件, 但可能会产生不一致的结果, 因为 IniRead 或其他应用程序通常无法正确读取它们.</p>
<p>标准的 ini 文件看起来类似下面这样:</p>
<pre>[SectionName]
Key=Value</pre>
<p>新文件将使用系统默认的 ANSI 代码页或者是 UTF-16, 这取决于 <a href="../Variables.htm#IsUnicode"> AutoHotkey 的版本</a>. UTF-16 可能会出现第一行为空行的情况, 因为第一行包含 UTF-16 字节顺序标记. 参考下面的解决方案.</p>
<p><b>Unicode:</b> IniRead 和 IniWrite 依靠外部函数 <a href="http://msdn.microsoft.com/en-us/library/ms724353.aspx">GetPrivateProfileString</a> 和 <a href="http://msdn.microsoft.com/en-us/library/ms725501.aspx">WritePrivateProfileString</a> 来读写值. 这些函数仅支持 Unicode 为 UTF-16 编码的文件; 其他所有文件都被认为使用系统默认的 ANSI 代码页. 在 <a href="../Variables.htm#IsUnicode">Unicode 脚本</a>中, IniWrite 为每个新文件使用 UTF-16 编码. 如果不希望这样, 那么请确保在执行 IniWrite 前目标文件已经存在. 例如:</p>
<pre>FileAppend,, NonUnicode.ini, CP0 <em>; 在大多数情况下最后一个参数是可选的.</em></pre>
<h2>相关</h2>
<p><a href="IniDelete.htm">IniDelete</a>, <a href="IniRead.htm">IniRead</a>, <a href="RegWrite.htm">RegWrite</a></p>
<h2>示例</h2>
<pre class="NoIndent">IniWrite, this is a new value, C:\Temp\myfile.ini, section2, key</pre>

</body>
</html>